home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / LIB / DESK / CORE / Desk / h_doc / Menu2 < prev    next >
Text File  |  1996-08-29  |  7KB  |  250 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Menu2.h
  12.     Author:  Copyright © 1995 Julian Smith
  13.     Version: 1.00 (22 Jun 1995)
  14.     Purpose: Easy menu handling
  15.     History:
  16.              1.10 (29 Aug 1996)    Added closefn.
  17. */
  18.  
  19.  
  20. #ifndef __Desk_Menu2_h
  21. #define __Desk_Menu2_h
  22.  
  23. #ifdef __cplusplus
  24.     extern "C" {
  25. #endif
  26.  
  27.  
  28. #ifndef __Desk_Menu_h
  29. #include "Desk.Menu.h"
  30. #endif
  31.  
  32.  
  33. /*
  34. Menu2
  35.  
  36. Menu2 provides a slightly higher-level interface to menus than the
  37. Menu library. It uses Menu functions. The application should
  38. supply up to four functions for each menu it uses. These functions are
  39. automatically called when required, to handle menu-choices, set
  40. menuflags, find submenus, and generate custom menus.
  41.  
  42. The Menu2 library automatically handles the re-opening of menus after an
  43. ADJUST choice, and also frees the menu data after a menu has closed.
  44.  
  45. If your app uses Menu2 then, when it starts up, it should call
  46. Desk_Menu2_Create for every menu it will use, and store the returned
  47. pointers.
  48.  
  49. These pointers are used to open menu in the future using Desk_Menu2_Open(),
  50. or to specify what submenu should be opened when required.
  51.  
  52. Note that Menu2 only creates menus when they are actually open, in order
  53. to save RMA memory.
  54.  
  55. There is also a function Desk_Menu2_AttachMenu which automatically opens
  56. menus in response to a click on an icon/window.
  57.  
  58. */
  59.  
  60.  
  61. typedef int    Desk_menu2_handle;
  62. /*
  63. This type is used to identify menus.
  64. */
  65.  
  66. typedef Desk_menu_ptr    (*Desk_menu2_makefn)( void *reference);
  67. /*
  68. This function-type should make a menu and return a pointer to it.
  69.  
  70. 'reference' is the reference originally passed to Desk_Menu2_Create for
  71. this menu.
  72.  */
  73.  
  74. typedef void    (*Desk_menu2_closefn)( Desk_menu_ptr menu, void *reference);
  75. /*
  76. This function-type is called when a menu is finished with (ie either a
  77. choice is made with 'Select' or 'Menu', or a Desk_message_MENUSDELETED
  78. message is received).
  79.  
  80. If a Desk_Menu2 menu has a makefn, you should provide a closefn which
  81. frees all data associated with the menu.
  82.  */
  83.  
  84. typedef void    (*Desk_menu2_flagsfn)( Desk_menu_ptr menu, void *reference);
  85. /*
  86. This function-type should set any flags in the menu. It will be called
  87. whenever the menu is created or reopened following an ADJUST
  88. menu-choice.
  89.  
  90. 'reference' is the reference originally passed to Desk_Menu2_Create for
  91. this menu.
  92.  */
  93.  
  94.  
  95. typedef void    (*Desk_menu2_selectfn)( int itemnum, void *reference);
  96. /*
  97. This function-type is called whenever a menu-choice is made. 'itemnum'
  98. determines the menu item-number which was chosen.
  99.  
  100. 'reference' is the reference originally passed to Desk_Menu2_Create for
  101. this menu.
  102.  
  103. Functions of this type shoule use globals such as Desk_Event_lastevent
  104. and Desk_menu_currentopen if they need to know more about the menu.
  105.  */
  106.  
  107. typedef Desk_menu2_handle    (*Desk_menu2_subfn)( int itemnum, Desk_event_pollblock *event, void *reference);
  108. /*
  109. This function-type is called whenever a submenu is required. 'itemnum'
  110. is the number of the menu item which needs a submenu, while 'event' is
  111. the original Desk_message_MENUWARN.
  112.  
  113. 'event' is included so that you can open a dialog box (or your own
  114. submenu menu) using the information in the Desk_message_menuwarn
  115. 'event->data.message.data.menuwarn'. If this is done, the function
  116. should return NULL, so that Menu2 knows that a submenu has been opened.
  117.  
  118. 'reference' is the reference originally passed to Desk_Menu2_Create for
  119. this menu.
  120.  */
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127. Desk_menu2_handle Desk_Menu2_Create( 
  128.     const char        *title,
  129.     const char        *spec,
  130.     Desk_menu2_makefn    makefn,     /* If !=NULL, called to make the menu    */
  131.     Desk_menu2_flagsfn    flagsfn,     /* Called every time menu is opened    */
  132.     Desk_menu2_subfn    subfn,         /* Called when submenu is needed    */
  133.     Desk_menu2_selectfn    selectfn,     /* Called when selection is made    */
  134.     Desk_menu2_closefn    closefn,    /* Called when menu is closed        */
  135.     void            *reference    /* Passed to the 5 fns above        */
  136.     );
  137. /*
  138. This returns a unique handle for a menu.
  139.  
  140. Returns 0 if unable to make the menu - eg not enough memory.
  141.  
  142. If 'makefn' is NULL, the menu will be made, when required, from 'title'
  143. and 'spec' using Desk_Menu_New. Otherwise, 'title' and 'spec' are ignored,
  144. and the 'makefn' is relied apon to make the menu and return a pointer to
  145. it.
  146.  
  147. If not NULL, 'closefn' will be called when the menu is finished (ie a
  148. choice made with SELECT or MENU, or a Desk_message_MENUSDELETED is
  149. received).
  150.  
  151. If 'makefn' is NULL, Desk_Menu2 will free the menu itself, with
  152. Desk_Icon_DisposeIndData and Desk_DeskMem_Free. Otherwise, you should
  153. provide a 'closefn' which frees the data created by 'makefn'.
  154.  
  155. NB 'title' and 'spec' are *not* copied, so they must point to permanent
  156. strings, or be NULL, in which case makefn must not be NULL.
  157. */
  158.  
  159.  
  160.  
  161. Desk_menu2_handle    Desk_Menu2_CreateFromMsgs(
  162.             const char        *titletag,
  163.             const char        *spectag,
  164.             Desk_menu2_makefn    makefn,
  165.             Desk_menu2_flagsfn    flagsfn,
  166.             Desk_menu2_subfn    subfn,
  167.             Desk_menu2_selectfn    selectfn,
  168.             Desk_menu2_closefn    closefn,
  169.             void            *reference
  170.             );
  171. /*
  172. Same as Desk_Menu2_Create, except the title and menu specification are read
  173. from a message file using Desk_Msgs_Lookup( titletag, ...) and Desk_Msgs_Lookup(
  174. spectag, ...) .
  175. */
  176.  
  177.  
  178. void    Desk_Menu2_Open( Desk_menu2_handle handle, int x, int y);
  179. /*
  180. This opens the specified menu. It uses Desk_Menu_Show, so use y=-1 if the
  181. menu is an iconbar menu.
  182. */
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189. void    Desk_Menu2_AttachMenu( 
  190.     Desk_window_handle    window, 
  191.     Desk_icon_handle    icon,
  192.     Desk_menu2_handle    menu,
  193.     int            button
  194.     );
  195. /*
  196. This uses Desk_Event_Claim to open a menu when the specified icon-window is
  197. clicked with the specified button(s). If the click is on the iconbar,
  198. the menu will be automatically opened in the correct position for
  199. iconbar menus.
  200.  
  201. Eg
  202.  
  203. Desk_Menu2_AttachMenu( w, i, specialmenu, Desk_button_MENU | Desk_button_SELECT);
  204. Desk_Menu2_AttachMenu( w, Desk_event_ANY, generalmenu, Desk_button_MENU);
  205.  
  206. See also: Desk_Menu2_DetachMenu.
  207. */
  208.  
  209.  
  210. void    Desk_Menu2_DetachMenu( 
  211.     Desk_window_handle    window, 
  212.     Desk_icon_handle    icon,
  213.     Desk_menu2_handle    menu,
  214.     int            button
  215.     );
  216. /*
  217. Stops the specified menu being opened when the icon-window is clicked
  218. with the specified button(s).
  219.  
  220. See also: Desk_Menu2_AttachMenu.
  221. */
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228. #ifdef Desk_DeskLib_DEBUG
  229.     #ifdef Desk__making_Menu2
  230.         #include "Debug.h"
  231.         #define Desk_debug_level Desk_menu2_debuglevel
  232.     #endif
  233.     
  234.     extern int    Desk_menu2_debuglevel;
  235. /*
  236. In the debug version of DeskLib, this is the Menu2 library's own
  237. version of Desk_debug_level. It is initially 0; a program can set it to
  238. different values to turn on different debug ouputs in the Menu2
  239. library.
  240.  */
  241. #endif
  242.  
  243.  
  244. #ifdef __cplusplus
  245. }
  246. #endif
  247.  
  248.  
  249. #endif
  250.